Monster Media 1994 #2

home *** CD-ROM | disk | FTP | other *** search

/ Monster Media 1994 #2 / Monster Media No. 2 (Monster Media)(1994).ISO / prog_c / dbpp20.zip / CLASSES.TXT next >

Wrap

Text File | 1994-05-09 | 20KB | 549 lines

CLASSES.DOC DataBase++ ver 2.00 classes --------------------------- This file contains a listing of all classes in DataBase++ along with a description of all public member functions (methods). TABLE OF CONTENTS ----------------- 1. DBObject 2. DBDatabase 3. DBIndexTag 4. DBStructure 5. DBArray 1. DBObject ------------ No member functions exist. You will not want to or need to create an instance of this class. 2. DBDatabase -------------- This is the core class of DataBase++ and is where most of the action occurs. It is responsible for creating, opening and manipulating database files. It contains a static data member (class variable) which tracks the number of instances of itself. The first created instance of a DBDatabase object will initialize CodeBase by calling it's d4init() function. The last DBDatabase object to be deleted will un-initialize CodeBase by calling it's d4init_undo() function. This is all done for you; you don't need to do it yourself. -------------------------------------------------------------------------------- DBDatabase() Construct a DBDatabase with no arguments. No data file is opened. -------------------------------------------------------------------------------- DBDatabase( char * fName ) Construct a DBDatabase using fName as the database file name. No data file is opened. -------------------------------------------------------------------------------- BOOL append() Appends a blank record to the data file. Returns TRUE if successful. -------------------------------------------------------------------------------- BOOL appendBlank() Same as append(). -------------------------------------------------------------------------------- BOOL bof() Returns TRUE if file pointer is at beginning of file; otherwise FALSE. -------------------------------------------------------------------------------- BOOL close() The data file is closed. If the file was never opened, nothing takes place. Returns TRUE if successful. -------------------------------------------------------------------------------- BOOL create( DBStructure& dbs ) Creates a data file from a DBStructure refference. Upon successful creation, the data file is opened. Returns TRUE if successful; else FALSE. Example: DBDatabase db( "test" ); DBStructure dbs; dbs.addField( "NAME", 'C', 20 ); // Add fields. dbs.addField( "AGE", 'N', 3 ); db.create( dbs ); -------------------------------------------------------------------------------- BOOL create( DBStructure& dbs, DBIndexTag& idx ) Creates a data file from a DBStructure refference and creates index files as well. Upon successful creation, the data file and index files are opened. Returns TRUE if successful; else FALSE. Example: DBDatabase db( "test" ); DBStructure dbs; DBIndexTag tag; dbs.addField( "NAME", 'C', 20 ); // Add fields. dbs.addField( "AGE", 'N', 3 ); tag.addTag( "TEST", "NAME" ); // Add tag definitions. db.create( dbs, tag ); -------------------------------------------------------------------------------- BOOL createIndex( DBIndexTag& idx ) An index file is created and opened for the given database from a DBIndexTag refference. Returns TRUE if successful; else FALSE. Example: DBDatabase db( "test" ); DBIndexTag tag; tag.addTag( "TEST", "NAME" ); // Add tag definitions. db.open(); db.createIndex( tag ); -------------------------------------------------------------------------------- void deleteRec() The record at the current record pointer is marked for deletion. The record is not actually removed until pack() is called. The record pointer remains on the record that is deleted. -------------------------------------------------------------------------------- BOOL deleted() Returns TRUE if the current record is marked for deletion; else FALSE. -------------------------------------------------------------------------------- BOOL eof() Returns TRUE if the record pointer is at end of file; else FALSE. -------------------------------------------------------------------------------- int fieldNum( char *fldName ) Returns the number of the field that matches fldName. If fldName is not a valid field in the data file, CodeBase will generate an error. -------------------------------------------------------------------------------- int fieldType( char *fldName ) Returns one of the following: 'C' - Character type 'N' - Numeric type 'D' - Date type 'L' - Logical type 'M' - Memo type. 'U' - Undefined type. -------------------------------------------------------------------------------- BOOL fileLock() The data file is locked. Returns TRUE if successful; else FALSE. -------------------------------------------------------------------------------- char * fileName() Returns the name of the file associated with the data file. -------------------------------------------------------------------------------- D4DATA * getD4DATA() Returns a pointer to CodeBase's D4DATA struct for the associated data file. This pointer is NULL if no data file has been opened. -------------------------------------------------------------------------------- char * getDate( char *fldName ) Returns the contents of a date field, fldName, as a string in the form of "MM/DD/YYYY\n". The string is stored in a CodeBase internal buffer and should be used immedialtely or copied to a local buffer. -------------------------------------------------------------------------------- double getDouble( char *fldName ) Returns a "numeric" field, fldName, as a double. -------------------------------------------------------------------------------- int getInt( char *fldName ) Returns a "numeric" field, fldName, as an int. -------------------------------------------------------------------------------- int getLogical( char *fldName ) Returns a "logical" field, fldName, as an int. -------------------------------------------------------------------------------- long getLong( char *fldName ) Returns a "numeric" field, fldName, as an long. -------------------------------------------------------------------------------- char * getMemo( char *fldName ) Returns the contents of the memo field, fldName, as a string. The string is stored in a CodeBase internal buffer and should be used immedialtely or copied to a local buffer. -------------------------------------------------------------------------------- char * getString( char *fldName ) Returns the contents of field, fldName, as a string. The string is stored in a CodeBase internal buffer and should be used immedialtely or copied to a local buffer. -------------------------------------------------------------------------------- void go( long nRecno ) Move record pointer to nRecno. -------------------------------------------------------------------------------- void goBottom(); Move record pointer to last record in file. -------------------------------------------------------------------------------- void goTop(); Move record pointer to first record in file. -------------------------------------------------------------------------------- char * indexTag() Return a pointer to the currently selected index tag name. Example: db.setIndexTag( "PRIMARY" ); db.indexTag(); // Returns "PRIMARY". -------------------------------------------------------------------------------- BOOL isOpen() Returns TRUE if file is open, else FALSE. -------------------------------------------------------------------------------- void memoPack() Packs the memo file. -------------------------------------------------------------------------------- int numFields() Returns the number of fields in the database. -------------------------------------------------------------------------------- BOOL open(); Opens the database file associated with the DBDatabase object. Returns TRUE if successful, else FALSE. If the file is already open, open() simply returns TRUE. -------------------------------------------------------------------------------- BOOL openIndex( char * indexFile ) Opens an index file. This method only applies when using Clipper or dBASE index files and DBF_GROUPS is not defined. Returns TRUE if index file opened successfully. -------------------------------------------------------------------------------- void pack( int mPack = 0 ) Packs the database, removing all records marked for deletion. If mPack is TRUE (non 0), memoPack() is called as well. -------------------------------------------------------------------------------- long reccount() Returns the number of records in the database. -------------------------------------------------------------------------------- void recall() Recalls a deleted record. -------------------------------------------------------------------------------- void reindex() Reindexes all index files associated with the database. -------------------------------------------------------------------------------- BOOL recLock() Locks a record. Returns TRUE if lock was successful, else FALSE. NOTE: You must call DBDatabase::SetMultiUser( TRUE ) to use network functions. -------------------------------------------------------------------------------- long recno() Returns the current record number. -------------------------------------------------------------------------------- void replace( char *fldName, char *str ) Replaces the field fldName with the string pointed to by str. -------------------------------------------------------------------------------- void replace( char *fldName, double d ) Replaces the field fldName with the double value d. -------------------------------------------------------------------------------- void replace( char *fldName, int i ) Replaces the field fldName with the integer value i. -------------------------------------------------------------------------------- void replace( char *fldName, long l ) Replaces the field fldName with the long value l. -------------------------------------------------------------------------------- BOOL seek( char *seekExpr ) Seeks the expression string pointed to by seekExpr using the current index tag. Returns TRUE if found, else FALSE. Example: db.setIndexTag( "NAMES" ); if ( db.seek( "JEFF" ) ) cout << "Found!" << endl; -------------------------------------------------------------------------------- void setFileName( char * fName ) Sets the file name of the DBDatabase object to fName. This has no effect on an open database. It allows you to create a DBDatabase with no file name and assign one at a later time. Example: DBDatabase db; db.setFileName( "test" ); db.open(); -------------------------------------------------------------------------------- void setFilter( FilterFunc ff ) Assigns the address of a user defined function which returns TRUE if the filter condition is met. FilterFunc is a typedef for a function pointer in the form of: typedef BOOL ( * FilterFunc )( DBDatabase & db ); All methods which result in the movement of the record pointer check to see if a filter function is set. If a filter function is provided, it is executed and if it returns FALSE, the record pointer is moved off the filtered record in the appropriate direction. Example which filters out all deleted records: // Your filter function BOOL MyFilter( DBDatabase &dbf ) { return( ! dbf.deleted() ); } // Set the filter function address. db.setFilter( MyFilter ); // Display all records that are not deleted. for ( db.goTop(); ! db.eof(); db.skip() ) cout << db.getString( "name" ) << endl; -------------------------------------------------------------------------------- BOOL setIndexTag( char *aTagName = NULL ) Sets the current index tag to aTagName. If aTagName == NULL, record order sorting is set. Example: db.setIndexTag( "PRIMARY" ); // Sets primary index tag. db.setIndexTag(); // Sets record order. -------------------------------------------------------------------------------- void skip( int nRecs = 1 ) Skips nRecs records in the database. nRecs defaults to 1. -------------------------------------------------------------------------------- void unlock() Removes all locks imposed on the file. -------------------------------------------------------------------------------- int unlockIndex() Unlocks the index files associated with the database. This is required by CodeBase if you are using CodeBase in multi user mode. It is required to be called after the movement of the record pointer for proper operation. You should never need to call unlockIndex() directly. -------------------------------------------------------------------------------- void zap( int mPack = 0 ) Removes all records in the database. If mPack is TRUE, memoPack() is called. USE WITH CARE, all records will be removed. -------------------------------------------------------------------------------- static C4CODE * CodeBase() Returns a pointer to the C4CODE structure used by CodeBase. -------------------------------------------------------------------------------- static char * GetCentury() Returns a pointer to a string which represents the current century used for date conversions. -------------------------------------------------------------------------------- static int Instances() Returns the number of instances of a DBDatabase object. -------------------------------------------------------------------------------- static int OpenFiles() Returns the number of open database files. -------------------------------------------------------------------------------- static void SetCentury( char *aCentury ) Sets the century string used in date conversions to aCentury. -------------------------------------------------------------------------------- static void SetMultiUser( BOOL state ) Sets the multi user state on or off. By default, multi user state is disabled. If state is TRUE, multi user mode is enabled and record and file locking techniques should be used. -------------------------------------------------------------------------------- static void CloseAll() Closes all open data files in all DBDatabase object instances. -------------------------------------------------------------------------------- 3. DBIndexTag -------------- DBIndexTag is responsible for constructing and manipulating collections of index tag definitions. You use it to specify a new index definition. Once a DBIndexTag object is filled with your tag descriptions, you can create indexes with it by calling DBDatabase::create() or DBDatabase::createIndexTag(). It's most notable method is addTag(), which adds a tag description. addTag() takes the following form: void addTag( char *tagName, char *expression, int unique = 0, int descending = 0 ); Example: DBDatabase db( "test" ); DBIndexTag dbTag; // Create a new tag definition called "NAMES" whose key is // "UPPER( LASTNAME )"... dbTag.addTag( "NAMES", "UPPER( LASTNAME )" ); // Open file. db.open(); // Create index tags. db.createIndex( dbTag ); 4. DBStructure --------------- DBStructure is responsible for constructing and manipulating collections of dataase field definitions. You use it to specify a new field definition. Once a DBStructure object is filled with your field descriptions, you can create database files with it by calling DBDatabase::create(). It's most notable method is addField(), which adds a field description. addField() takes the following form: void addField( char *fldName, char type, int len, int dec = 0 ); Example: DBDatabase db( "test" ); DBStructure dbs; // Create some fields. dbs.addField( "NAME", 'C', 30 ); dbs.addField( "AGE", 'N', 3 ); dbs.addField( "BIRTHDATE", 'D', 8 ); dbs.addField( "SALARY", 'N', 8, 2 ); dbs.addField( "NOTES", 'M', 10 ); // Create file. db.create( dbs ); 5. DBArray ----------- DBArray is an array class which stores pointers to DBObject types and it's descendents. It is used in the DBDatabase, DBIndexTag and DBStructure classes. Member functions: -------------------------------------------------------------------------------- DBArray( int sz = 1, int growBy = 1 ) Construct a DBArray. sz controls the initial maximum number of DBObject pointers that will fit in the array. growBy controls the number of DBObject pointers that the array will expand by if the sz limit is exceeded. -------------------------------------------------------------------------------- void add( DBObject *anObject ) Adds a pointer to a DBObject pointer pointed to by anObject. -------------------------------------------------------------------------------- int itemsInArray() Returns the number of items in the array. -------------------------------------------------------------------------------- void ownsObjects( unsigned bool ) Sets the ownership status of the object pointers in the array. If bool == TRUE (the default), the objects contained in the array will be destroyed by the array when the array goes out of scope. If bool == FALSE, the objects will not be deleted. -------------------------------------------------------------------------------- void remove( int index ) Removes an object pointer at index. If index is out of range, nothing happens. If the array owns the objects, the object is deleted. -------------------------------------------------------------------------------- void remove( DBObject *anObject ) Removes an object pointer whose address matches anObject. If the array owns the objects, the object is deleted. -------------------------------------------------------------------------------- DBObject * operator [] ( int index ) Returns the object pointer at index. --------------------------------------------------------------------------------